add missing step for gem-based theme conversion #6802
Conversation
docs/_docs/themes.md
Outdated
| @@ -3,7 +3,7 @@ title: Themes | |||
| permalink: /docs/themes/ | |||
| --- | |||
|
|
|||
| Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site's content. | |||
| Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package up plugins, assets, layouts, includes, and stylesheets in a way that can be overridden by your site's content. | |||
There was a problem hiding this comment.
Theme-gems do not package plugins. The gemspec only specifies gem-based plugins that are then required by Jekyll while loading the theme-gem.
*.rb files in a _plugins directory in the theme-gem will not be loaded whatsoever (as of v3.7.x)
docs/_docs/themes.md
Outdated
| @@ -108,7 +108,33 @@ Suppose you want to get rid of the gem-based theme and convert it to a regular t | |||
|
|
|||
| To do this, copy the files from the theme gem's directory into your Jekyll site directory. (For example, copy them to `/myblog` if you created your Jekyll site at `/myblog`. See the previous section for details.) | |||
|
|
|||
| Then remove references to the theme gem in `Gemfile` and configuration. For example, to remove `minima`: | |||
| Then you must tell Jekyll about the plugins that were packaged by the theme. You can find these plugins in the theme's gemspec file as runtime dependencies. If you were converting the Minima theme, for example, you might see: | |||
There was a problem hiding this comment.
here as well.. plugins are not packaged by the theme, just referenced to..
- about the plugins that were packaged by the theme. You can find these plugins in the theme's gemspec...
+ about the plugins that are required by the theme. You can find these plugins listed in the theme's gemspec...
|
Thank you. Correction attempted. |
|
/cc @jekyll/documentation |
| ```ruby | ||
| # ./Gemfile | ||
|
|
||
| group :jekyll_plugins do |
There was a problem hiding this comment.
If using group :jekyll_plugins, the plugins do not need to be added to _config.yml
There was a problem hiding this comment.
Note: GitHub Pages do not require plugins via Bundler. So adding to _config.yml is always better
There was a problem hiding this comment.
Could be listed as an either/or.
There was a problem hiding this comment.
I think I understand. I've attempted to incorporate these notes. Please check for accuracy and style.
|
I like this. This does a really good job of explaining what the issue is, and how to work around it. |
|
Thanks! |
docs/_docs/themes.md
Outdated
|
|
||
| Either way, don't forget to `bundle update`. | ||
|
|
||
| However, if you're publishing on GitHub Pages you should update only your `_config.yml` as GitHub Pages doesn't require plugins via Bundler. |
There was a problem hiding this comment.
one small correction here:
- GitHub Pages doesn't require plugins
+ GitHub Pages doesn't load pluginswhile require is technically correct in Ruby-lingo, the English equivalent 'load' is better suited here
There was a problem hiding this comment.
great. I was concerned about that. Fixed.
|
@jekyllbot: merge +docs |
Theme documentation steps for converting a gem-based theme into 'intrinsic' site files are missing explanation about plugins.
First brought up in jekyll/minima#157
h/t @ashmaroli
@jekyll/documentation